Xbasic GuideCalling Xbasic Scripts in Your Applications
Web and mobile applications execute Xbasic using Ajax callbacks. Ajax callbacks allow you to retrieve data from or send data to the server without needing to reload an application. Examples of operations that use Ajax callbacks include uploading a file, fetching the next set of records to display in a Grid component, creating and downloading a report, or saving data to a database.
How does an Ajax Callback work?
An Ajax callback is an asynchronous exchange of messages between the client application (a web browser or mobile device) and the Alpha Anywhere Application Web Server. The user performs an action that triggers an Ajax callback. The callback is done by making a JavaScript function call that includes the Xbasic script to call and any additional information you would like to send to the server. After the callback is made, the application continues executing -- it does not wait for a response.
When the server receives the callback, it executes the requested server-side Xbasic script. After execution completes, a response containing JavaScript to execute is sent back to the calling application. When the application receives the response, it runs the JavaScript from the server.
Where are Ajax Callback Functions Defined
A Callback Function is the Xbasic script executed when you make an Ajax callback. The function is commonly defined in the component's Xbasic Functions section during application design. To the call the Xbasic function, an Ajax Callback Action can be added to a control (such as a button) using the Action Javascript builder.
The Ajax Callback Action requires, at a minimum, the name of the Xbasic function to call. The Ajax Callback Action builder includes two helpful links for generating the Xbasic function for the callback: Create function prototype and Open Xbasic Function Declarations.
To generate the Xbasic function, you must first give the function a name -- defined in the Function name property.
Once you have named the function, you can then click on the Create function prototype to generate the Xbasic callback function.
Create function prototype generates the Xbasic required for the Ajax callback, including code comments that provide information about the arguments passed to the function, available system objects (such as session), and expected return values.
When the Function prototype appears, use the "Copy to Clipboard" button at the bottom of the Ajax Callback Function Prototype dialog to copy the Xbasic then close the dialog.
Then, click on "Open Xbasic Function Declarations" to access the Xbasic Functions section of the component.
The Xbasic Functions section is where you can define Xbasic functions for use in Ajax callbacks and server-side events. Paste the code into the Xbasic editor, and then close the editor and save your Action Javascript.
You can modify your Xbasic Function on the Xbasic Functions pane of the component. The image below shows where to find the Xbasic Functions pane in the Grid and UX Components.
Server-side Events
Xbasic is used in component server-side events. Server-side events are special Xbasic functions called when the component code executes on the server. For example, when a UX component is first loaded, the Xbasic onDialogInitialize server-side event is called.
Ajax callbacks also trigger server-side events. For example, when the {dialog.object}.submit() function is called, which makes an Ajax callback to submit data from the UX component to the server, it triggers the following server-side events in the order shown:
Some common use cases for server-side events include data validation, saving data to a database, customizing the component layout, calling a stored procedure, or computing initialization data, such as the choices for dropdown boxes or radio buttons.
Server-side Events Exercise: Populating a Dropdown Box
A dropdown control's choices can be dynamically populated using an Xbasic variable. The variable can be a session variable or a variable created in the onDialogInitialize server-side event.
Create a new blank UX Component and add a dropdown box control from the Data controls section. Open the dropdown box control's Choices and select the Variable option in the Define Choices dialog. Enter "dropdownChoices" in the Variable name box and click OK to save the settings.
Next, click on Server-side in the left-hand menu to open the Server-Side events. Select the onDialogInitialize event. Add a new line on line 2 and paste the following script into the Xbasic editor:
DIM places AS C = <<%txt% Canberra,Australia Brasilia,Brazil Ottawa,Canada Santiago,Chile Copenhagen,Denmark Tokyo,Japan Mexico City,Mexico Rabat,Morocco Wellington,New Zealand Oslo,Norway Lima,Peru Vanuatu,Port Vila Cape Town,South Africa Stockholm,Sweden Harare,Zimbabwe %txt% e.rtc.dropdownChoices = places
Save the component and run it in Live or Working Preview. Click on the dropdown box to display the list of choices.
Persisting Data Beyond the End of a Callback
Thus far, we have only discussed creating local variables. A local variable in Xbasic only exists for the duration of the script in which the variable was created. When the script finishes execution, local variables cease to exist.
In an application, there are many cases where you may want to store data on the server beyond the end of the script's execution, such as the logged in user's name, the name of a recently uploaded file, or custom settings for the application. This type of information can be saved between callbacks using session variables.
What are Session Variables
Session variables are stored in the context.session object. The context object is a global Xbasic object available to any Xbasic script throughout a web application. It contains the session object where you can create variables to store data for the current user's session.
Creating Session Variables
Session variables are created by adding a property to the context.session object. For example:
context.session.country = "Canada"
All session variables are character type variables. In order to store data such as dates, numbers, arrays, or object pointers in a session variable, they must be converted to a character string.
For simple data types (such as dates, time, or logical), the easiest way to convert a value to a character is to concatenate it with an empty character value. For example:
DIM number AS N = 5 DIM string AS C string = "" + number context.session.myNumber = string
Complex objects such as arrays and object pointers need to be serialized to a character string before they can be stored in the session. Serializing data is done using the json_generate() method to convert the array or pointer variable to a JSON string. For example:
DIM person AS P person.name = "John Smith" person.city = "Boston" person.state = "MA" ' Serialize p to a character string context.session.obj = json_generate(person) ? context.session.obj = { "name": "John Smith", "city": "Boston", "state": "MA" }What about GLOBAL and SHARED variables?
If you have visited the online documentation on declaring Xbasic variables, you may have noticed that variables can be declared as GLOBAL or SHARED. These keywords will create Xbasic variables that can be accessed outside of an Xbasic function. The only way to create variables that exist beyond the end of a script in desktop applications is using the GLOBAL or SHARED keywords.
In web applications, however, GLOBAL and SHARED variables do not behave in the same way. GLOBAL and SHARED variables only exist for the duration of the Ajax callback in web applications. Once the callback completes, GLOBAL and SHARED Xbasic variables no longer exist. Because of this, you must store data that you would like to reference in other callbacks and scripts in session variables.
Reading Session Variables
Session variables can be read from the context.session object. For example:
DIM usercontact AS C IF (variable_exists("context.session.userEmail")) THEN usercontact = context.session.userEmail END IFWhen you read the value from the session variable, you can use the convert_type() method to cast the data to the desired type. convert_type() allows you to convert any data type to any other data type. If you have stored numeric values in a session variable, you would use convert_type(context.session.myNumber,"N") to cast the session variable to a numeric type. For example:
DIM num2 AS N ' Convert session.myNumber to a number num2 = convert_type(context.session.myNumber, "N")
If the session variable was created by serializing an array or object pointer using the json_generate() function, you can convert the json object back to a pointer variable with json_parse():
DIM person2 AS P ' Deserialize context.session.obj to a pointer variable person2 = json_parse(context.session.obj) ? person2 = city = "Boston" name = "John Smith" state = "MA"
Session Variable Availability
Before using a session variable, you must verify that the session variable exists. Attempting to use a session variable that doesn't exist, or was deleted because the session is no longer active, will result in a runtime error. You can prevent this error by using the variable_exists() function to test that the session variable is available before trying to use it.
DIM myNumber AS N IF (variable_exists("context.session.myNumber")) THEN myNumber = convert_type(context.session.myNumber,"N") END IFWhen a session variable is created, it is available for the duration of the session. The session will remain active as long as the following conditions are met:
- The Application Server is not stopped or restarted.
- The next interaction (page request or update) occurs within the Application Server within the session lifetime interval. The minimum value for this interval is 300 seconds (5 minutes); the interval is set in the Application Server settings.
- The session is not reset or abandoned.